home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 007a / pv050doc.zip / PVRAY05.DOC < prev    next >
Text File  |  1991-09-08  |  17KB  |  457 lines
  1.    Persistence of Vision Raytracer 
  2.    Version 0.5 BETA Documentation
  3. -----------------------------------------
  4.  
  5.  For general documentation see PVDOC.ZIP.
  6. Also see whatsnew.txt, texture.doc, docformt.txt, pvteam.txt, etc.
  7. These docs are fairly sparse this time around. We're working on better
  8. ones now.
  9.  
  10. This is a BETA version, so please keep those bug reports comin'! 
  11.  
  12.  INTERPOLATE keyword added for bump and image maps.
  13.  Syntax: interpolate 2 or interpolate 4
  14.          2 == Bilinear Interpolation
  15.          4 == Normalized Distance Interpolation
  16.  USE_COLOUR keyword added for maps.
  17.  USE_INDEX keyowrd added for maps.
  18.  END_MAP keyword added for maps.
  19.  
  20.  IMPORTANT Case sensitivity 
  21.  --------------------------
  22.   Case sensitive keywords and command line option added.
  23.    > case_sensitive_yes -- All words checked for exact case. Keywords must be
  24.                            in upper case. (*Old DKB Style*)
  25.    > case_sensitive_no  -- Case is ignored for all words.
  26.    > case_sensitive_opt -- DEFAULT - All words checked for exact case except
  27.                            keywords. Keywords will be accepted in upper and/or
  28.                            lower case. 
  29.  - The declared colors Red, Green, and Blue in colors.dat are now CRed, CBlue,
  30.    CGreen.
  31.  - The declared quadric Sphere in shapes.dat is now QSphere.
  32.  - The texture Sky is now Blue_Sky
  33.  
  34.  COMMAND LINE Options  
  35.  --------------------  
  36.  > Case sensitivity -- /ty = yes, /tn = no, /to = opt (see above)
  37.  
  38.  +vO will enable old style terse verbose, line number only.
  39.  +v0 will enable old new style verbose.
  40.  +v1 (default) will enable new improved style verbose.
  41.  
  42.  
  43.  New IBM-PC display options
  44.  --------------------------
  45.  +dxy enables display adapter type x, with palette option y.
  46.  
  47.    Supported Display Adapter Types:
  48.  
  49.      0 - (default) Autodetect display adapter from types below:
  50.      1 - Basic, Plain Vanilla VGA 320x200
  51.      2 - MVGA (Mode 13X) Tweaked VGA 360x480 (if > 320x200)
  52.      3 - Tseng Labs 3000 SVGA 640x350, 640x480, 800x600
  53.      4 - Tseng Labs 4000 SVGA 640x350, 640x400, 640x480, 800x600, 1024x768
  54.      5 - AT&T VDC600 SVGA 640x400 (with cheesy autodetect)
  55.      6 - Oak Technologies OTI-067 SVGA 640x480
  56.      7 - Video 7 SVGA, VRAM FastRAM 640x480
  57.      8 - Video 7 Vega VGA, Cirrus Chip (uses Mode 1 or 2 above)
  58.      9 - Paradise SVGA 640x480
  59.      A - Ahead Systems Version A SVGA 640x480
  60.      B - Ahead Systems Version B SVGA 640x480
  61.      C - Chips And Technologies SVGA 640x480
  62.      D - ATI VGA Wonder 640x480
  63.      E - Everex SVGA 640x480
  64.      F - Trident SVGA 640x480
  65.      G - VESA Standard SVGA 640x400, 640x480, 800x600, 1024x768, 1280x1024
  66.  
  67.      H - N reserved, unassigned (S)VGA adapter types
  68.  
  69.      O - TIGA/Hercules Graphics Workstation 16-bit
  70.      P - TIGA/Hercules Graphics Workstation 24-bit
  71.  
  72.      Q - Z reserved, unassigned True-Color adapter types
  73.  
  74.    Supported Palette Options:
  75.  
  76.      0 - (default) HSV->RGB method
  77.      3 - 3-3-2 RGB method
  78.      G - Grey Scale (optimized 64-shade palette for IBM PC's)
  79.      H - Sierra High Color pallete DAC
  80.  
  81.  
  82. TEXTURES
  83. -------- 
  84.  
  85. We don't have documentation for ONION & LEOPARD yet, but their syntax
  86. is the same as GRANITE or MARBLE. They do require a COLOR_MAP.
  87. Try them out.
  88.  
  89.  
  90. MAPTYPE - Works with imagemap, bumpmap and material map.
  91. New stuff is a set of new image projection types.  To specify an
  92. imagemap, an additional parameter is optional, i.e.
  93.  
  94.    IMAGEMAP MAPTYPE 1 GIF "xxx.gif" END_MAP
  95.  
  96. Gives a spherical image map.  The types of imagemaps that are now
  97. defined are:
  98.  
  99.    0) (default) Planar map - this is the one that was already there.
  100.    
  101.    1) Spherical map - wraps the image around a sphere.
  102.    2) Cylindrical map - wraps the image around a cylinder (works good for
  103.       hyperboloids, cones, and paraboloids too).
  104.    5) Torus map - wraps the image around a torus.  For this map you need
  105.       to put the major radius of the torus into the first parameter of the
  106.       gradient vector.
  107.  
  108.    3-4) Parabolic and Hyperbolic maps - these are not implemented yet, but
  109.       will be tailored for mapping to the respective types.  The reason for
  110.       having these in addition to the cylindrical types is that these shapes
  111.       deflect differently than a cylinder.    
  112.    
  113.    NOTE: Gradient only effects planar mapping.
  114.  
  115. For all of these image mappers it is assumed that the imagemap will work
  116. in the interval 0 <= Y <= 1.  This means that you need to use the shapes:
  117. QUADRIC QSphere, QUADRIC Cylinder_Y, QUADRIC Hyperbola_Y, etc.  If the default
  118. Planar mapping is used, no object dimensions or coordinates need be changed.
  119.  
  120. See the file "mapper.dat" and the associated gif file "mapper0.gif" for an
  121. example of how the new various types of mappers work.  This file wraps the
  122. picture "rough.gif" around various shapes.
  123.  
  124.  
  125. KEYWORD: MATERIAL_MAP
  126.  
  127. BRIEFLY:
  128.  MATERIAL_MAP maps textures onto an object indexed via a bit-mapped image.
  129.  
  130. SYNTAX:
  131.  MATERIAL_MAP <orientation> Image-Type "imagefilename" (ONCE) (TURBULENCE 0.0)
  132.   (MAPTYPE #)
  133.   TEXTURE ... END_TEXTURE
  134.   TEXTURE ... END_TEXTURE
  135.   (up to 256 textures)  
  136.  
  137.  END_MATERIAL_MAP 
  138.  
  139. DESCRIPTION:
  140.   MATERIAL_MAP is a lot like IMAGE_MAP. Image map takes a picture and 
  141.   projects it onto an image. Like gluing a picture onto a sphere. Material
  142.   map does the same, but instead of changing the color of the sphere it 
  143.   actually changes the texture of the sphere based on the color in the image.
  144.   When it finds a point that would have color number 0 projected on it, it
  145.   changes that point to the first texture in the MATERIAL_MAP definition. 
  146.   Color index number 1 will become texture number 2 and so on.
  147.  
  148. EXAMPLE:
  149.  OBJECT
  150.    SPHERE <0.0  25.0  0.0>  50.0 END_SPHERE
  151.  
  152.    TEXTURE        { X-Y oriented bitmap image }
  153.     MATERIAL_MAP <1.0 -1.0 0.0> GIF "pvmap.gif" 
  154.     
  155.       TEXTURE 
  156.        COLOR Yellow       
  157.        SPECULAR 0.75
  158.        SCALE <7.0 1.5 3.0> 
  159.       END_TEXTURE
  160.       TEXTURE
  161.        Mirror      
  162.        SPECULAR 0.75
  163.       END_TEXTURE
  164.       TEXTURE
  165.        Dark_Wood
  166.        SPECULAR 0.75
  167.       END_TEXTURE
  168.       TEXTURE
  169.         Jade
  170.         SPECULAR 0.75 
  171.       END_TEXTURE
  172.      
  173.      END_MATERIAL_MAP
  174.      ROTATE <0.0 35.0 0.0>
  175.      SCALE < 15.0 15.0 15.0 >   
  176.    END_TEXTURE
  177. END_OBJECT
  178.  
  179.  
  180. KEYWORD: BUMPMAP
  181.  
  182. BRIEFLY:
  183.  BUMPMAP maps surface "bumps" onto an object indexed via a bit-mapped image.
  184.  
  185. SYNTAX:
  186.  BUMPMAP (<orientation>) Image-Type "imagefilename" (ONCE) (TURBULENCE 0.0)
  187.  (BUMPSIZE Height or Depth) (USE_COLOR) (USE_INDEX)
  188.  (INTERPOLATE 2 or 4)
  189.  (MAPTYPE #)
  190.  END_MAP
  191.  
  192. DESCRIPTION:
  193.   BUMPMAP is a lot like IMAGEMAP.  IMAGEMAP takes a picture and projects it
  194.   onto an image, like gluing a picture onto a sphere.  BUMPMAP does the same,
  195.   but instead of changing the color of the sphere it actually changes the
  196.   orientation of the surface normal based on the colors in the image.
  197.   When it finds a point that would have color number 0 projected on it, it
  198.   leaves that point's surface normal alone.  Color index number 1 will become
  199.   "bumped" out from the flat surface, color number 2 further still, and so on.
  200.   Try using one of FRACTINT's continuous potential fractals for interesting
  201.   BUMPMAP effects! BUMPSIZE can be negative. Try USE_COLOUR and INTERPOLATION.
  202.  
  203. EXAMPLE:
  204.  OBJECT
  205.    SPHERE <0.0  25.0  0.0>  50.0 END_SPHERE
  206.  
  207.    TEXTURE        { X-Y oriented bitmap image }
  208.       BUMPMAP <1.0 -1.0 0.0> GIF "bumpy.gif"
  209.       BUMPSIZE 3.0  {Try values from negative to very high }
  210.       INTERPOLATE 2
  211.       END_MAP
  212.       AMBIENT 0.2
  213.       DIFFUSE 0.8
  214.       SPECULAR 1.0
  215.    END_TEXTURE
  216.  
  217.    ROTATE <0.0 35.0 0.0>
  218.    SCALE < 15.0 15.0 15.0 >
  219.    END_TEXTURE
  220. END_OBJECT
  221.  
  222.  
  223. KEYWORD: GOUGEMAP
  224.  
  225. BRIEFLY:
  226.  GOUGEMAP maps indentations into an object indexed via a bit-mapped image.
  227.  
  228. SYNTAX:
  229.  GOUGEMAP <orientation> Image-Type "imagefilename" (ONCE) (TURBULENCE 0.0)
  230.  (GOUGESIZE Depth or BUMPSIZE Depth )
  231.  END_MAP
  232.  
  233. DESCRIPTION:
  234.   GOUGEMAP is a lot like IMAGEMAP.  IMAGEMAP takes a picture and projects it
  235.   onto an image, like gluing a picture onto a sphere.  GOUGEMAP does the same,
  236.   but instead of changing the color of the sphere it actually changes the
  237.   orientation of the surface normal based on the colors in the image.
  238.   When it finds a point that would have color number 0 projected on it, it
  239.   leaves that point's surface normal alone.  Color index number 1 will become
  240.   indented from the flat surface, color number 2 further still, and so on.
  241.   GOUGEMAP uses a failed BUMPMAP code that some of us thought produced an
  242.   interesting effect. It may or may not be in the final version.
  243.  
  244. EXAMPLE:
  245.  OBJECT
  246.    SPHERE <0.0  25.0  0.0>  50.0 END_SPHERE
  247.  
  248.    TEXTURE        { X-Y oriented bitmap image }
  249.       GOUGEMAP <1.0 -1.0 0.0> GIF "scratchy.gif"
  250.       GOUGESIZE 1.0  {typ. between 0 and 1.  Try > 1 for really deep gouges }
  251.       AMBIENT 0.3
  252.       DIFFUSE 0.7
  253.       PHONG 1.0
  254.    END_TEXTURE
  255.  
  256.    ROTATE <0.0 35.0 0.0>
  257.    SCALE < 15.0 15.0 15.0 >
  258.    END_TEXTURE
  259. END_OBJECT
  260.  
  261.  
  262.  
  263. POLYNOMIAL SURFACES
  264. -------------------
  265.  
  266. Polynomials of arbitrary degree are handled by one of the following
  267. declarations:
  268.  
  269.    CUBIC < 10 Coefficients > END_CUBIC,
  270.  
  271.    QUARTIC < 35 Coefficients > END_QUARTIC,
  272.  
  273.    POLY < Max-Degree > < (n+1)*(n+2)*(n+3)/6 Coefficients > END_POLY
  274.  
  275. Quartics are the only case handled as a seperate case, with code to solve
  276. them specifically.  Higher order polynomial surfaces are solved using
  277. Sturmian sequences.  (The root solver is based on code from "Graphics Gems"
  278. by Glassner, and is not debugged.  Use at your own risk for surfaces of
  279. degree higher than 4.)  Cubics and quartics seem to be safe - the code for
  280. these surfaces is the same as previous versions and suffers only from
  281. precisions problems leading to digital noise.
  282.  
  283. See "SINSURF.DAT" for a 6th order surface.  So far I haven't gotten a good
  284. render of it as a result of system crashes and too much time spent working
  285. on bicubic patches.
  286.  
  287.  
  288. CLIPPING
  289. --------
  290.  
  291. The keywords CLIPPED_BY and END_CLIP have been added to allow for chopping
  292. parts of a surface by another surface.  The effect is identical to an
  293. INTERSECTION with a transparent surface, but quite a bit faster.  See
  294. "GRAFBIC.DAT" for a Bicorn that has had its front and back chopped.
  295.  
  296.  
  297. BICUBIC PATCHES
  298. ---------------
  299.  
  300. Bicubic patches are a mesh of control points that describe the shape of
  301. a surface.  There are several types of bicubic patches, however the only
  302. one currently understood is the Bezier patch.
  303.  
  304. Bezier patches are bicubic patches that take on the values of the corner
  305. vertices of the mesh, and are influenced by the other values.  A notable
  306. computer graphic object that has this sort of patch definition is the
  307. UTAH Teapot. (See TEAPOT.DAT.)
  308.  
  309. In order to ray-trace a patch, the patch is approximated by a mesh of vertices
  310. that interpolate the patch.  By increasing the number of points in each of
  311. the two mesh parameters (u, and v), a smoother approximation to the true grid
  312. will be traced.  NOTE: Increasing the number of points increases the amount
  313. of work in proportion to U-Resolution * V-Resolution.  If the patch is going
  314. to be small on the screen then you will not need to use a very high resolution.
  315.  
  316. The definition of a BICUBIC patch takes the form:
  317.  
  318.    BICUBIC_PATCH <Patch Type> <U resolution> <V resolution>
  319.       < vertex (0,0) > < vertex (0,1) > < vertex (0,2) > < vertex (0,3) >
  320.       < vertex (1,0) > < vertex (1,1) > < vertex (1,2) > < vertex (1,3) >
  321.       < vertex (2,0) > < vertex (2,1) > < vertex (2,2) > < vertex (2,3) >
  322.       < vertex (3,0) > < vertex (3,1) > < vertex (3,2) > < vertex (3,3) >
  323.  
  324.       [ <texture>, <translate>, <rotate>, ... ]
  325.    END_BICUBIC
  326.  
  327. The value of "Patch Type" determines the shading characteristics of the
  328. patch, and the amount of storage used for mesh constants.  There are
  329. currently three allowed values for "Patch Type":
  330.  
  331.  
  332.    0) Bezier patch, only sufficient storage is allocated to store the tri-
  333.       angular vertices.
  334.  
  335.    1) Bezier patch, vertices, all plane equations defined by the triangulation
  336.       of the patch into subpatches are stored.
  337.  
  338.    2) Bezier patch, using binary subdivision to find the point of surface
  339.       intersection.
  340.  
  341.    3) Bezier patch, using binary subdivision, with vertices and all values
  342.       precomputed and stored.
  343.  
  344.    4) Bezier patch, vertices, all plane equations, normals at each vertex of
  345.       a subpatch are stored (to be used for a SMOOTH_TRIANGLE shading in each
  346.       of subpatch).
  347.  
  348. At some future date, other types of patches besides Bezier may be used.  In
  349. this case new values of Patch Type will be defined for them.
  350.  
  351. The value of "U Resolution" determines the number of steps along the
  352. U parameter (row variable) that are taken when subdividing the patch.
  353.  
  354. The value of "V Resolution" determines the number of steps along the
  355. V parameter (column variable) that are taken when subdividing the patch. 
  356.  
  357. An example of a Bezier patch is:
  358.  
  359.    BICUBIC_PATCH 1 4 4
  360.       < 0.0  0.0  2.0>  < 1.0  0.0  0.0>  < 2.0  0.0  0.0>  < 3.0  0.0 -2.0>
  361.       < 0.0  1.0  0.0>  < 1.0  1.0  0.0>  < 2.0  1.0  0.0>  < 3.0  1.0  0.0>
  362.       < 0.0  2.0  0.0>  < 1.0  2.0  0.0>  < 2.0  2.0  0.0>  < 3.0  2.0  0.0>
  363.       < 0.0  3.0  2.0>  < 1.0  3.0  0.0>  < 2.0  3.0  0.0>  < 3.0  3.0 -2.0>
  364.    END_BICUBIC
  365.  
  366. This is a patch that is interpolated by a 4x4 mesh of vertices.  This is
  367. subdivided into 2x4x4 = 32 triangles.  This second subdivision into triangles
  368. is algorithmic and occurs in two situatons, when the patch is parsed and when
  369. intersections are being calculated.  In addition the plane equation of all
  370. 32 triangles are stored so that intersection calculations can be optimized
  371. a bit.
  372.  
  373. If the Patch Type were changed from 1 to 3, normal calculations based on the
  374. normal to the patch at each of the mesh vertices would be used.  This gives
  375. the same shading effect that SMOOTH_TRIANGLE's have.
  376.  
  377. For example, the following patch definition has taken 16 co-planar points
  378. arranged in the grid 0 <= x <= 1 && 0 <= y <= 1 && z = 0, and pulled two
  379. corners down and two corners up along the z-axis. (See BEZIER.DAT.)
  380.  
  381. OBJECT
  382.    BICUBIC_PATCH 1 4 4
  383.       < 0.0  0.0  2.0>  < 1.0  0.0  0.0>  < 2.0  0.0  0.0>  < 3.0  0.0 -2.0>
  384.       < 0.0  1.0  0.0>  < 1.0  1.0  0.0>  < 2.0  1.0  0.0>  < 3.0  1.0  0.0>
  385.       < 0.0  2.0  0.0>  < 1.0  2.0  0.0>  < 2.0  2.0  0.0>  < 3.0  2.0  0.0>
  386.       < 0.0  3.0  2.0>  < 1.0  3.0  0.0>  < 2.0  3.0  0.0>  < 3.0  3.0 -2.0>
  387.       TEXTURE CHECKER COLOR RED 1.0 COLOR BLUE 1.0 ROTATE <90 0 0>
  388.               AMBIENT 0.1 DIFFUSE 0.9 PHONG 1 END_TEXTURE
  389.    END_BICUBIC
  390.    TRANSLATE <-1.5 -1.5 0>
  391.    SCALE <2 2 2>
  392.    ROTATE <30 -70 0>
  393.    BOUNDED_BY SPHERE <0 0 0> 6 END_SPHERE END_BOUND
  394. END_OBJECT
  395.  
  396.  
  397. STURMIAN SEQUENCES
  398. ------------------
  399.  
  400. There have been many improvements in calcluating 3rd and 4th order surfaces.
  401. By default they are still computed the same was as previously, but there is
  402. a new and better way:  Sturmian Sequences! - these seem to cure the majority
  403. of problems with math precision errors resulting in digital acne or outright
  404. noise bursts in the QUARTIC shapes.  The classic error-prone TEARDROP file
  405. now runs beautifully!  This takes care of some of the worst of the problems,
  406. but seems to lead to occasional problems when the normal is calculated (the
  407. surface is correct but the shading is sometimes a little off).  The bad
  408. shading isn't totally random either - it often makes sort of swirl patterns.
  409. In order to use the Sturmian Sequence method, place the keyword STURM anywhere
  410. after the end of the vectors inside a Cubic, Quartic or Bicubic Patch shape
  411. definition.
  412.  
  413. Example:
  414.  
  415. OBJECT
  416.    QUARTIC
  417.    < 1.0   0.0   0.0    0.0     2.0   0.0   0.0   2.0   0.0 -104.0
  418.      0.0   0.0   0.0    0.0     0.0   0.0   0.0   0.0   0.0    0.0
  419.      1.0   0.0   0.0    2.0     0.0  56.0   0.0   0.0   0.0    0.0
  420.      1.0   0.0 -104.0   0.0   784.0 >
  421.    STURM { <-----<<< Must be placed before the END_ statement! <----<<<< }
  422.    END_QUARTIC
  423.    .
  424.    .
  425.    .
  426. END_OBJECT
  427.  
  428.  
  429. DECLARED CONSTANTS
  430. ------------------
  431.  
  432. Here are the various types of constants allowed by the DECLARE statement:
  433.  
  434. OBJECT_CONSTANT
  435. SPHERE_CONSTANT
  436. PLANE_CONSTANT
  437. TRIANGLE_CONSTANT
  438. SMOOTH_TRIANGLE_CONSTANT
  439. QUADRIC_CONSTANT
  440. POLY_CONSTANT (QUARTIC)
  441. POLY_CONSTANT (CUBIC)
  442. POLY_CONSTANT (POLY)
  443. BICUBIC_PATCH_CONSTANT
  444. CSG_INTERSECTION_CONSTANT
  445. CSG_UNION_CONSTANT
  446. CSG_DIFFERENCE_CONSTANT
  447. COMPOSITE_CONSTANT
  448. TEXTURE_CONSTANT
  449. VIEW_POINT_CONSTANT
  450. COLOUR_CONSTANT
  451. VECTOR_CONSTANT
  452. FLOAT_CONSTANT
  453.  
  454. Smile - 
  455.  
  456. If you cannot afford a texture block, a default one will be appointed to you!
  457.